

    \filetitle{matrix}{Insert matrix or numeric array}{report/matrix}

	\paragraph{Syntax}\label{syntax}

\begin{verbatim}
P.matrix(Caption,Data,...)
\end{verbatim}

\paragraph{Input arguments}\label{input-arguments}

\begin{itemize}
\item
  \texttt{P} {[} struct {]} - Report object created by the
  \href{report/new}{\texttt{report.new}} function.
\item
  \texttt{Caption} {[} char \textbar{} cellstr {]} - Title or a cell
  array with title and subtitle displayed at the top of the matrix; see
  Description for splitting the title or subtitle into multiple lines.
\item
  \texttt{Data} {[} numeric {]} - Numeric array with input data.
\end{itemize}

\paragraph{Options}\label{options}

\begin{itemize}
\item
  \texttt{'arrayStretch='} {[} numeric \textbar{} \emph{\texttt{1.15}}
  {]} - (Inheritable from parent objects) Stretch between lines in the
  matrix (in pts).
\item
  \texttt{'captionTypeface='} {[} cellstr \textbar{} char \textbar{}
  *'\large\bfseries'* {]} - \LaTeX\\format commands for typesetting the
  matrix caption; the subcaption format can be entered as the second
  cell in a cell array.
\item
  \texttt{'colNames='} {[} cellstr \textbar{} \emph{empty} {]} -
  (Inheritable from parent objects) Names for individual matrix columns,
  displayed at the top of the matrix.
\item
  \texttt{'colWidth='} {[} numeric \textbar{} \emph{\texttt{NaN}} {]} -
  (Inheritable from parent objects) Width, or a vector of widhts, of the
  matrix columns in \texttt{em}units; \texttt{NaN} means the width of
  the column will adjust automatically.
\item
  \texttt{'condFormat='} {[} struct \textbar{} \emph{empty} {]} -
  (Inheritable from parent objects) Structure with .test and .format
  fields describing conditional formatting of individual matrix entries.
\item
  \texttt{'footnote='} {[} char \textbar{} \emph{empty} {]} - Footnote
  at the matrix title; only shows if the title is non-empty.
\item
  \texttt{'format='} {[} char \textbar{} \emph{\texttt{'\%.2f'}} {]} -
  (Inheritable from parent objects) Numeric format string; see help on
  the built-in \texttt{sprintf} function.
\item
  \texttt{'heading='} {[} char \textbar{} \emph{empty} {]} -
  (Inheritable from parent objects) User-supplied heading, i.e.~an extra
  row or rows at the top of the matrix.
\item
  \texttt{'inf='} {[} char \textbar{}
  \emph{\texttt{'\$\textbackslash{}infty\$'}} {]} - (Inheritable from
  parent objects) \LaTeX~string that will be used to typeset Infs.
\item
  \texttt{'long='} {[} \texttt{true} \textbar{} \emph{\texttt{false}}
  {]} - (Inheritable from parent objects) If \texttt{true}, the matrix
  may stretch over more than one page.
\item
  \texttt{'longFoot='} {[} char \textbar{} \emph{empty} {]} -
  (Inheritable from parent objects) Works only with \texttt{'long='}
  \texttt{true}: Footnote that appears at the bottom of the matrix (if
  it is longer than one page) on each page except the last one.
\item
  \texttt{'longFootPosition='} {[} \texttt{'centre'} \textbar{}
  \emph{\texttt{'left'}} \textbar{} \texttt{'right'} {]} - (Inheritable
  from parent objects) Works only with \texttt{'long='} \texttt{true}:
  Horizontal alignment of the footnote in long matrices.
\item
  \texttt{'nan='} {[} char \textbar{}
  \emph{\texttt{'\$\textbackslash{}cdots\$'}} {]} - (Inheritable from
  parent objects) \LaTeX~string that will be used to typeset
  \texttt{NaN}s.
\item
  \texttt{'pureZero='} {[} char \textbar{} \emph{empty} {]} -
  (Inheritable from parent objects) \LaTeX~string that will be used to
  typeset pure zero entries; if empty the zeros will be printed using
  the current numeric format.
\item
  \texttt{'printedZero='} {[} char \textbar{} \emph{empty} {]} -
  (Inheritable from parent objects) \LaTeX~string that will be used to
  typeset the entries that would appear as zero under the current
  numeric format used; if empty these numbers will be printed using the
  current numeric format.
\item
  \texttt{'rotateColNames='} {[} \emph{\texttt{true}} \textbar{}
  \texttt{false} \textbar{} numeric {]} - Rotate the names of columns by
  the specified number of degrees; \texttt{true} means rotate by 90
  degrees.
\item
  \texttt{'rowNames='} {[} cellstr \textbar{} \emph{empty} {]} -
  (Inheritable from parent objects) Names fr individual matrix rows,
  displayed left of the matrix.
\item
  \texttt{'separator='} {[} char \textbar{}
  \emph{\texttt{'\textbackslash{}medskip\textbackslash{}par'}} {]} -
  (Inheritable from parent objects) \LaTeX~commands that will be
  inserted after the matrix.
\item
  \texttt{'sideways='} {[} \texttt{true} \textbar{}
  \emph{\texttt{false}} {]} - (Inheritable from parent objects) Print
  the matrix rotated by 90 degrees.
\item
  \texttt{'tabcolsep='} {[} \texttt{NaN} \textbar{} numeric {]} -
  (Inheritable from parent objects) Space between columns in the matrix,
  measured in em units; \texttt{NaN} means the \LaTeX~default.
\item
  \texttt{'typeface='} {[} char \textbar{} \emph{empty} {]} - (Not
  inheritable from parent objects) \LaTeX~code specifying the typeface
  for the matrix as a whole; it must use the declarative forms (such as
  \texttt{\textbackslash{}itshape}) and not the command forms (such as
  \texttt{\textbackslash{}textit\{...\}}).
\end{itemize}

\paragraph{Generic options}\label{generic-options}

See help on \href{report/Contents}{generic options} in report objects.

\paragraph{Description}\label{description}

\subparagraph{Conditional formatting}\label{conditional-formatting}

The conditional format struct (or an array of structs) specified through
the \texttt{'condFormat='} option must have two fields, \texttt{.test}
and \texttt{.format}.

The \texttt{.test} field is a text string with a Matlab expression. The
expression must evaluate to a scalar \texttt{true} or \texttt{false},
and can refer to the following attributes associated with each entry in
the data part of the matrix:

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{value} - the numerical value of the entry;
\item
  \texttt{row} - the row number within the data part of the matrix;
\item
  \texttt{col} - the column number within the data part of the matrix;
\item
  \texttt{rowname} - the row name right of which the entry appears;
\item
  \texttt{colname} - the column name under which the entry appears;
\item
  \texttt{rowvalues} - a row vector of all values in the current row;
\item
  \texttt{colvalues} - a column vector of all values in the current
  column;
\item
  \texttt{allvalues} - a matrix of all values.
\end{itemize}

You can combine a number of attribues within one test, using the logical
operators, e.g.

\begin{verbatim}
value > 0 && row > 3
value == max(rowvalues) && strcmp(rowname,'x')
\end{verbatim}

The \texttt{.format} fields of the conditional format structure consist
of LaTeX commands that will be use to typeset the corresponding entry.
The reference to the entry itself is through a question mark. The
entries are typeset in math mode; this for instance meanse that for bold
or italic typface, you must use the
\texttt{\textbackslash{}mathbf\{...\}} and
\texttt{\textbackslash{}mathit\{...\}} commands.

In addition to standard LaTeX commands, you can use the following IRIS
commands in the format strings:

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{\textbackslash{}sprintf\{FFFF\}} - to modify the way each
  numeric entry that passes the test is printed by the \texttt{sprintf}
  function; \texttt{FFFF} is one of the standard sprintf formattting
  strings.
\end{itemize}

You can combine multiple tests and their correponding formats in one
structure; they will be all applied to each entry in the specified
order.

\subparagraph{Titles and subtitles}\label{titles-and-subtitles}

The input argument \texttt{Caption} can be either a text string, or a
1-by-2 cell array of strings. In the latter case, the first cell will be
printed as a title, and the second cell will be printed as a subtitle.

To split the title or subtitle into multiple lines, use the following
LaTeX commands wrapped in curly brackets:
\texttt{\{\textbackslash{}\textbackslash{}\}} or
\texttt{\{\textbackslash{}\textbackslash{}{[}Xpt{]}\}}, where \texttt{X}
is the width of an extra vertical space (in points) added between the
respective lines.

\paragraph{Example}\label{example}


